home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Extras / IFF / Old_IFF_Packages / November_1988 / Documents / Code.doc < prev    next >
Encoding:
Text File  |  1989-02-23  |  4.7 KB  |  118 lines
  1.         Overview of EA IFF example source files
  2.  
  3.  
  4. This source code is distributed as public domain software. Use it to help
  5. write robust IFF-compatible programs.
  6.  
  7. Caveat: Electronic Arts developed this code, and is releasing it to promote
  8. the success of the Amiga.  EA does not have the resources to supply support
  9. for this code. For support, Amiga software developers contact Commodore
  10. directly.
  11.  
  12. 1. Description of the EA-provided sources and include files
  13.  
  14.     COMPILER.H    Portability file to isolate compiler idiosyncrasies.
  15.  
  16.     INTUALL .H    A super-include file for Amiga include files.
  17.  
  18.     REMALLOC.H    Header for RemAlloc subroutines.
  19.     REMALLOC.C    Memory ALLOCators which REMember the size allocated,
  20.             for simpler freeing.
  21.  
  22.     GIO    .H    Header file for Generic I/O speed up package.
  23.     GIO    .C    Generic I/O speed up routines (a disk cache).
  24.     GIOCALL .C    Outline of example GIO client.
  25.             To turn on the GIO package, change a switch in GIO.H,
  26.             add GIO.O to the linker control file, and recompile.
  27.  
  28.     IFF    .H    Header file for general IFF read/write support.
  29.     IFFR    .C    IFF reader support routines.
  30.     IFFW    .C    IFF writer support routines.
  31.             These routines do a lot of the work for reading and
  32.             writing IFF files robustly. The reader and writer are
  33.             separate since some programs don't need both.
  34.  
  35.     IFFCHECK.C    IFF checker utility source (very handy for debugging).
  36.             The IFF checker scans an IFF file, checks it for
  37.             syntax errors, and prints an outline of its contents.
  38.  
  39.     PACKER    .H    Header for byte run encoder (compressor) subroutines.
  40.     PACKER    .C    Run encoder subroutines.
  41.     UNPACKER.C    Run decoder subroutines. This run encoder/decoder is
  42.             used for ILBM raster images.
  43.  
  44.     ILBM    .H    Header for ILBM (raster image file) subroutines.
  45.     ILBMR    .C    ILBM reader support routines. Uses IFFR.
  46.     ILBMW    .C    ILBM writer support routines. Uses IFFW.
  47.  
  48.     READPICT.H    Header for ReadPicture subroutines.
  49.     READPICT.C    ReadPicture subroutines read an ILBM file into an
  50.             Amiga BitMap in RAM. Uses ILBMR and IFFR.
  51.  
  52.     SHOWILBM.C    Example program that reads and displays an ILBM file.
  53.  
  54.     PUTPICT .H    Header for PutPict subroutines.
  55.     PUTPICT .C    PutPict subroutines write an Amiga BitMap from RAM
  56.             to an ILBM file. Uses ILBMW and IFFW.
  57.  
  58.     RAW2ILBM.C    Example program that reads a "raw" raster image file
  59.             and writes the image as an ILBM file.
  60.  
  61.     ILBM2Raw.C    Example program that reads an image as an ILBM file
  62.             and writes the image as a "raw" raster image file.
  63.  
  64.     BMPrintC.C    Subroutine that actually does the text dump.
  65.     ILBMDump.C    Example program that reads an image as an ILBM file
  66.             and writes the image as a text file containing C data
  67.             initialization statements for either a BOB or a
  68.             Sprite.
  69.  
  70. 2. Compiler idiosyncracies.
  71.  
  72. This source code was built for the Lattice 68000 Amiga C cross-compiler, and
  73. the Metacomco ALink linker. Some of the IFF source code assumes that the
  74. compiler will support function protyping: the ability to typecheck procedure
  75. arguments (templates). Believe me, typechecking is useful! The more bugs I
  76. find at compile time, the less I have to find at run time.
  77.  
  78. The programmer asks for this typechecking via an "extern" statement like
  79. this:
  80.     extern IFFP Seek(BPTR, LONG, LONG);
  81.     typedef IFFP ClientProc(struct _GroupContext *);
  82.  
  83. Unfortunately, this chokes some C compilers. If you have such a compiler, you
  84. have to comment out the stuff in parentheses. The above two examples become:
  85.  
  86.     extern IFFP Seek(/* BPTR, LONG, LONG */);
  87.     typedef IFFP ClientProc(/* struct _GroupContext * */);
  88.  
  89. Don't remove the parentheses!
  90.  
  91. The header file COMPILER.H defines macros to isolate the compiler
  92. dependencies. The macro FDwAT ("function definitions with argument types")
  93. switches on/off the argument type declarations in the header files in this
  94. directory.
  95.  
  96.  
  97. 3. RemAlloc subroutines.
  98.  
  99. The "REMembering ALLOCator" is a useful little subroutine package included
  100. here. It saves you from having to remember the size of each node you
  101. allocate. (Why doesn't the Amiga allocator do this?)
  102.  
  103.  
  104. 4. Optional buffered file I/O package GIO.
  105.  
  106. Amiga file I/O can be greatly sped up by use of a RAM buffer. So we now have
  107. a layer of software that provides optional buffering. Some compilers may also
  108. have such a layer, in which case ignore this one. The "option" is controlled
  109. by changing a "#define" inside the header file GIO.H, adding GIO.O to your
  110. link file, recompiling, and recompiling. When turned off, this layer becomes
  111. just a layer of macro calls between the IFFR and IFFW modules and the
  112. AmigaDOS routines they call.
  113.  
  114. This RAM buffer speeds things up when you're doing numerous small Writes
  115. and/or Seeks while writing. The general IFF writer IFFW.C tends to do this.
  116. It should be extended to optimize reading, too. If you are not using IFF, and
  117. already Write in chunks of 256 bytes or more, don't bother using GIO.
  118.